HBASE-17823 Update to Yetus Audience Annotations #58

busbey · 2017-08-30T21:43:45Z

@mstanleyjones

mdlinville

I tried rewording some of these. It would have been easier if I could just make these changes on top of yours, but I couldn't apply your patch b/c of conflicts and I gave up. 👼

mdlinville · 2017-08-30T22:04:03Z

src/main/asciidoc/_chapters/upgrading.adoc

@@ -125,10 +125,10 @@ for warning about incompatible changes). All effort will be made to provide a de
 [[hbase.client.api.surface]]
 ==== HBase API Surface

-HBase has a lot of API points, but for the compatibility matrix above, we differentiate between Client API, Limited Private API, and Private API. HBase uses a version of link:https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/Compatibility.html[Hadoop's Interface classification]. HBase's Interface classification classes can be found link:https://hbase.apache.org/apidocs/org/apache/hadoop/hbase/classification/package-summary.html[here].
+HBase has a lot of API points, but for the compatibility matrix above, we differentiate between Client API, Limited Private API, and Private API. HBase uses link:http://yetus.apache.org/documentation/0.5.0/interface-classification/[Apache Yetus Audience Annotations] to guide downstream expectations for stability. In previous releases HBase relied on its own implementation of these classes; folks can rely on the same assumptions based on the annotation class name, but the package will be different.


I suggest breaking out Client API, Limited Private API, and Private API into a little table or list with definitions of each.

The last sentence is kind of inside baseball. I suggest something like "HBase no longer maintains its own implementation of these classes but relies on packages provided by Apache Yetus.

a table independent of the explanation in the InterfaceAudience section below? or in place of?

In place of.

just to confirm. there is a set of sub-sections under here that has brief definitions of each of Client API, LP API, and private API:

http://hbase.apache.org/book.html#hbase.client.api.surface

I'm turning those into a table?

It's not that important. I think I just sensed that the info was both confusing and kind of matrix-y.

mdlinville · 2017-08-30T22:08:50Z

src/main/asciidoc/_chapters/upgrading.adoc


-* InterfaceAudience: captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields.
-* InterfaceStability: describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated. Notice that this annotation is only valid for classes which are marked as IA.LimitedPrivate. The stability of IA.Public classes is only related to the upgrade type(major, minor or patch). And for IA.Private classes, there is no guarantee on the stability between releases. Refer to the Compatibility Matrix above for more details.
+* InterfaceAudience (link:http://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceAudience.html[javadocs]): captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields.


intended audience. Possible values include:

Public: safe for use by end users and external projects

LimitedPrivate: safe for use for projects which need access to HBase internals, such as coprocessors or other plugin points

Private: only for internal use within HBase itself

Classes which are defined as IA.Private may be used as parameters or return values for interfaces which are declared IA.LimitedPrivate. Treat the IA.Private object as a monolithic object when using it as a parameter to call other methods or when returning it, but do not try to access its methods or fields directly.

mdlinville · 2017-08-30T22:15:59Z

src/main/asciidoc/_chapters/upgrading.adoc

-* InterfaceAudience: captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields.
-* InterfaceStability: describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated. Notice that this annotation is only valid for classes which are marked as IA.LimitedPrivate. The stability of IA.Public classes is only related to the upgrade type(major, minor or patch). And for IA.Private classes, there is no guarantee on the stability between releases. Refer to the Compatibility Matrix above for more details.
+* InterfaceAudience (link:http://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceAudience.html[javadocs]): captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields.
+* InterfaceStability (link:http://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceStability.html[javadocs]): describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated. Notice that this annotation is only valid for classes which are marked as IA.LimitedPrivate. The stability of IA.Public classes is only related to the upgrade type(major, minor or patch). And for IA.Private classes, there is no guarantee on the stability between releases. Refer to the Compatibility Matrix above for more details.


permitted. Possible values include:

Stable: the interface is fixed and is not expected to change.

Evolving: the interface is relatively fixed, but may change <when?>

Unstable: the interface may change at any time

Deprecated: plan to update your code to use a non-deprecated class instead.

The following interactions occur between InterfaceAudience and `InterfaceStability:

iA.Public classes are inherently stable, and adhere to the stability guarantees relating to the type of upgrade (major, minor, or patch).

InterfaceStability may be any of the allowed values when InterfaceStability is IA.LimitedPrivate.

IA.Private classes should be considered inherently unstable, with no guarantee of stability between releases.

(I'm not sure where Deprecated fits here, because you can definitely have Pubic things that are deprecated -- that's the whole point, right?)

looking at both yetus and our own internal IS settings, there is no Deprecated. so I'll just remove references to it.

busbey · 2017-09-10T17:58:59Z

rebasing this is super painful, so I'd like to avoid doing it another time after the one I'm doing now. Presuming I can get all of these feedback changes in place, are you +1 @mstanleyjones?

busbey · 2017-09-11T07:29:33Z

I think I have your feedback in place, let me know how things look.

mdlinville

LGTM, I'll comment on the JIRA too.

Co-authored-by: Scott Williams <[email protected]>

This reverts commit 4143495.

mdlinville suggested changes Aug 30, 2017

View reviewed changes

busbey added 2 commits September 11, 2017 00:22

HBASE-17823 Migrate to Apache Yetus Audience Annotations

0502127

HBASE-17823 addedum with docs update

0cac54f

busbey force-pushed the HBASE-17823 branch from 8e1f53d to 0cac54f Compare September 11, 2017 07:27

mdlinville approved these changes Sep 11, 2017

View reviewed changes

busbey closed this Sep 26, 2017

busbey deleted the HBASE-17823 branch September 26, 2017 14:05

Apache-HBase mentioned this pull request Aug 5, 2019

HBASE-22776 Rename config names in user scan snapshot feature #440

Merged

This was referenced Sep 6, 2019

HBASE-22927 Upgrade Mockito version for jdk11 #593

Merged

HBASE-23005 Table UI showed exception message when table is disabled #607

Closed

HBASE-22971 Deprecated RSGroupAdminEndpoint and make RSGroup feature … #595

Merged

This was referenced Oct 12, 2019

HBASE-23152 Compaction_switch does not work by RegionServer name #713

Merged

HBASE-23174 Upgrade jackson and jackson-databind to 2.9.10 (branch-1) #724

Merged

HBASE-22749: Distributed MOB compactions #623

Closed

This was referenced Oct 22, 2019

HBASE-23199 Error populating Table-Attribute fields #741

Merged

HBASE-23181 Blocked WAL archive: "LogRoller: Failed to schedule flush of XXXX, because it is not online on us" #742

Closed

ndimiduk pushed a commit to ndimiduk/hbase that referenced this pull request Feb 29, 2024

revert 20 days (apache#58)

4143495

Co-authored-by: Scott Williams <[email protected]>

ndimiduk pushed a commit to ndimiduk/hbase that referenced this pull request Feb 29, 2024

Revert "revert 20 days (apache#58)" (apache#59)

162d297

This reverts commit 4143495.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HBASE-17823 Update to Yetus Audience Annotations #58

HBASE-17823 Update to Yetus Audience Annotations #58

busbey commented Aug 30, 2017

mdlinville left a comment

mdlinville Aug 30, 2017

busbey Sep 10, 2017

mdlinville Sep 10, 2017

busbey Sep 11, 2017

mdlinville Sep 11, 2017

mdlinville Aug 30, 2017

mdlinville Aug 30, 2017

busbey Sep 10, 2017

busbey commented Sep 10, 2017

busbey commented Sep 11, 2017

mdlinville left a comment

HBASE-17823 Update to Yetus Audience Annotations #58

HBASE-17823 Update to Yetus Audience Annotations #58

Conversation

busbey commented Aug 30, 2017

mdlinville left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

busbey commented Sep 10, 2017

busbey commented Sep 11, 2017

mdlinville left a comment

Choose a reason for hiding this comment